<HTML>
<TITLE>module clouds</TITLE>
<BODY BGCOLOR="#AABBCC" TEXT="#332211" >

<DIV ALIGN="CENTER"> <FONT SIZE=1>
<A HREF="#INTERFACE">PUBLIC INTERFACE</A> / 
<A HREF="#ROUTINES">ROUTINES</A> / 
<A HREF="#NAMELIST">NAMELIST</A> / 
<A HREF="#DIAGNOSTICS">DIAGNOSTICS</A> / 
<A HREF="#CHANGES">CHANGES</A> / 
<A HREF="#ERRORS">ERRORS</A> / 
<A HREF="#REFERENCES">REFERENCES</A> / 
<A HREF="#NOTES">NOTES</A> 
</FONT>
<BR><BR></DIV><HR>


<H2>Module Clouds</H2>
<A NAME="HEADER">
<PRE>
     <B>Contact:</B>   Bruce Wyman
     <B>Reviewers:</B>

     <B><A HREF=".doc.log#clouds.f90">Tags/Status</A></B>
</PRE>
</A><!-- END HEADER -->
<!--------------------------------------------------------------------->
<A NAME="OVERVIEW">
<HR>
<H4>OVERVIEW</H4>
<!-- BEGIN OVERVIEW -->
<PRE>

     Driver for generating the cloud properties consistent with the
     radiation scheme.

</PRE>
</A><!-- END OVERVIEW -->
<!--------------------------------------------------------------------->
<A NAME="DESCRIPTION">
<!-- BEGIN DESCRIPTION -->
<PRE>

     This version returns cloud amounts and radiative properties
     in the "compressed" format used by the Fels-Schwarzkopf
     radiation package.

</PRE>
</A><!-- END DESCRIPTION -->
<!--------------------------------------------------------------------->
<A NAME="MODULES_USED">
<HR>
<H4>OTHER MODULES USED</H4>
<!-- BEGIN MODULES_USED -->
<PRE>

     cloud_zonal_mod
       cloud_obs_mod
       rh_clouds_mod
     strat_cloud_mod
      diag_cloud_mod
       cloud_rad_mod
    time_manager_mod
    diag_manager_mod
       utilities_mod

</PRE>
</A><!-- END MODULES_USED -->
<!--------------------------------------------------------------------->
<A NAME="INTERFACE">
<HR>
<H4>PUBLIC INTERFACE</H4>
<!-- BEGIN INTERFACE -->
<PRE>

   use clouds_mod [, only: clouds_init, clouds, clouds_end ]

   clouds_init - Called once to initialize the module

   clouds      - Called every (radiation) time step to set up the
                 the clouds and their radiative properties.

   clouds_end  - Does nothing.

   NOTES:
     1) Namelist interface &clouds_nml if provided must be in file
        input.nml.
     2) A version number and namelist variables are appended to
        file logfile.out.

</PRE>
</A><!-- END INTERFACE -->
<!--------------------------------------------------------------------->
<A NAME="ROUTINES">
<HR>
<H4>PUBLIC ROUTINES</H4>
<!-- BEGIN ROUTINES -->
<PRE>

<b>call clouds_init</b> (lonb, latb, axes, Time)

 Input

      lonb   The longitude in radians for all grid box boundaries.
               [real, dimension(:)]

      latb   The latitude in radians for all grid box boundaries.
               [real, dimension(:)]

      axes    The axis indices that are returned by previous calls to
              diag_axis_init. The values of this array correspond to the
              x, y, full (p)level, and half (p)level axes. These are the
              axes that diagnostic fields are output on.
                 [integer, dimension(4)]

      Time    The current time.  [time_type]

 Notes

    1) If nlon is the number of longitude points in the global grid,
       then lonb should be dimensioned by nlon+1.

    2) If nlat is the number of latitude points in the global grid,
       then latb should be dimensioned by nlat+1.

----------------------------------------------------------------------

call clouds  (is, js, clear_sky, Time, Time_diag, lat, land, 
              tsfc, pfull, phalf, t, q, cosz,
              nclds, ktopsw, kbtmsw, ktopsw, kbtmlw,
              cldamt, cuvrf, cirrf, cirab, emcld
              [, mask, kbot] )

 Input

     is,js       The starting i,j indices of a sub-grid window. [integer]

     clear_sky   Flag indicating whether a clear_sky calculation is done.
                 If this is set to true, there will be no clouds.
                   [logical]

     Time        The current (radiative) time.  [time_type]

     Time_diag   The time used when outputting diagnostic fields.
                    [time_type]

     lat         The latitude in radians.  [real, dimension(:,:)]

     land        The fractional amount of a grid box covered by land.
                   [real, dimension(:,:)]

     tsfc        Surface skin temperature (Kelvin) [real, dimension(:,:)]

     pfull       Pressure in pascals at full model levels.
                   [real, dimension(:,:,nlev)]

     phalf       Pressure in pascals at half model levels.
                   [real, dimension(:,:,nlev+1)]

     t           Temperature in deg K at full model levels.
                   [real, dimension(:,:,nlev)]
 
     q           Water vapor specific humidity at full model levels.
                   [real, dimension(:,:,nlev)]
    
     cosz        Cosine of the zenith angle.
                   [real, dimension(:,:)]

 Output

     nclds       The number of clouds in a vertical column at each grid box.
                   [integer, dimension(:,:)]

     ktopsw,     The top and bottom index (at layer interfaces)
       kbtmsw    of the "nclds" clouds for shortwave calculations.
                   [integer, dimension(:,:,nlev+1)]

     ktopsw,     The top and bottom index (at model levels)
       kbtmlw    of the "nclds" clouds for longwave calculations.
                   [integer, dimension(:,:,nlev+1)]

     cldamt      The fractional cloud amount of the "nclds" clouds.
                   [real, dimension(:,:,nlev+1)]

     cuvrf       The fractional amount of ultraviolet radiation reflected
                 by the "nclds" clouds.  [real, dimension(:,:,nlev+1)]

     cirrf       The fractional amount of infrared radiation reflected
                 by the "nclds" clouds.  [real, dimension(:,:,nlev+1)]

     cirab       The fractional amount of infrared radiation absorbed
                 by the "nclds" clouds.  [real, dimension(:,:,nlev+1)]

     emcld       The emissivity for the "nclds" clouds.
                   [real, dimension(:,:,nlev+1)]

 Input (optional)

     mask       mask (1. or 0.) for grid boxes above or below
                the ground, usually only necessary for the step-mountain
                (eta) vertical coordinate  [real, dimension(:,:,nlev)]

     kbot        The index of the model level immediately above the ground.
                 If grid boxes do not lie below the ground, then this argument
                 does not need to be supplied. The default is nlev.
                   [integer, dimension(:,:)]

 Output (optional)

     tca         The total cloud amount computed by assuming that independent
                 clouds overlap randomly.  [real, dimension(:,:)]

 Notes

   1) The first two dimensions correspond to a sub-window of the
      horizontal grid. The first dimension is longitude and the
      second is latitude. Their location is defined by the cloud_init
      interface.

----------------------------------------------------------------------

call clouds_end ( )

   This routine has no arguments and currently does nothing.

</PRE>
</A><!-- END ROUTINES -->
<!--------------------------------------------------------------------->
<A NAME="NAMELIST">
<HR>
<H4>NAMELIST</H4>
<!-- BEGIN NAMELIST -->
<PRE>

<b>&clouds_nml</b>

   do_zonal_clouds    flag that specifies that zonal (London) clouds
                      will be used
                        [logical, default: do_zonal_clouds = .false.]

   do_obs_clouds      flag that specifies that observed (ISCCP)
                      clouds will be used, the cloud positions will
                      be the same as the zonal (London) clouds.
                        [logical, default: do_obs_clouds = .false.]

   do_no_clouds       flag that specifies that no clouds will be used
                        [logical, default: do_no_clouds = .false.]

   do_isccp_cloud_diags  When .true., specifies alternative cloud scheme
                         for the pupose of cloud diagnostics.
			 Intended for use with the Manabe Climate Model.
                        [logical, default: do_no_clouds = .false.]

<b>Notes:</b>
    1) If do_zonal_clouds = do_obs_clouds = do_no_clouds = .false.
       and a predicted cloud scheme has not been used then by default
       zonal clouds will be used.

</PRE>
</A><!-- END NAMELIST -->
<!--------------------------------------------------------------------->
<A NAME="DIAGNOSTICS">
<HR>
<H4>DIAGNOSTIC FIELDS</H4>
<PRE>
Diagnostic fields may be output to a netcdf file by specifying the
module name <b>clouds</b> and the desired field names (given below)
in file <b>diag_table</b>. See the documentation for diag_manager.
</PRE>
<!-- BEGIN DIAGNOSTICS -->
<PRE>

Diagnostic fields for module name: <b>clouds</b>

   field name      field description
   ----------      -----------------

   tot_cld_amt     total cloud amount (percent)
   high_cld_amt    high cloud amount (percent)
   mid_cld_amt     middle cloud amount (percent)
   low_cld_amt     low cloud amount (percent)
   cld_amt         cloud amount (percent)
   em_cld          cloud emissivity (none)
   alb_uv_cld      UV reflected by cloud (none)
   alb_nir_cld     IR reflected by cloud (none)
   abs_uv_cld      UV absorbed by cloud (none)
   abs_nir_cld     IR absorbed by cloud (none)

NOTES:

   If namelist variable do_no_clouds = .true., there will be no 
   diagnostic fields saved.

</PRE>
</A><!-- END DIAGNOSTICS -->
<!--------------------------------------------------------------------->
<A NAME="CHANGES">
<HR>
<H4>CHANGE HISTORY</H4>
<!-- BEGIN CHANGES -->
<PRE>
<B><A HREF=".doc.log#clouds.f90">CVS revision history</A></B>

<b>changes from 10/4/1999</b>

     MPP version created. Minor changes for open_file, error_mesg,
     and Fortran write statements. Answers should reproduce the
     previous version.

<b>prior changes<b>

   * The namelist control for predicted cloud schemes (strat_cloud 
     and rh_clouds) was moved to module moist_processes. Predicted
     cloud scheme interaction in this module is controlled through
     interfaces.

</PRE>
</A><!-- END CHANGES -->
<!--------------------------------------------------------------------->
<A NAME="ERRORS">
<HR>
<H4>ERROR MESSAGES</H4>
<!-- BEGIN ERRORS -->
<PRE>

<b>Fatal Errors from clouds in clouds_mod:</b>

   <b>input arrays have the incorrect size.</b>
        The third dimension (i.e., level) is not consistent between
        input arguments. Variable at full levels should be dimensioned
        by nlev, while variables at half levels should be dimensioned
        by nlev+1.

</PRE>
</A><!-- END ERRORS -->
<!--------------------------------------------------------------------->
<A NAME="REFERENCES">
<HR>
<H4>REFERENCES</H4>
<!-- BEGIN REFERENCES -->
<PRE>

     None.

</PRE>
</A><!-- END REFERENCES -->
<!--------------------------------------------------------------------->
<A NAME="COMPILER">
<HR>
<H4>COMPILER SPECIFICS</H4>
<!-- BEGIN COMPILER -->
<PRE>

     None.

</PRE>
</A><!-- END COMPILER -->
<!--------------------------------------------------------------------->
<A NAME="BUGS">
<HR>
<H4>KNOWN BUGS</H4>
<!-- BEGIN BUGS -->
<PRE>

     None.

</PRE>
</A><!-- END BUGS -->
<!--------------------------------------------------------------------->
<A NAME="NOTES">
<HR>
<H4>NOTES</H4>
<!-- BEGIN NOTES -->
<PRE>

 1) The ground pressure is normalize to 101325 Pa so that with
    prescribed clouds there will always be three cloud levels.

 2) The observed clouds only provide amounts. The position (model level)
    and radiative properties are the same that used for zonal clouds.

 3) RH_CLOUDS, STRAT_CLOUD, or DIAG_CLOUD will override specified clouds
    (when their restart data is available). The predicted cloud schemes
    are controlled through module moist_processes.

 4) Default cloud properties for specified clouds are set up
    in module zonal_cloud.

 5) If optional argument "kbot" is present (i.e., the eta coordinate
    option), then a cloud is placed in the underground portion of
    the column. For prescribed clouds, this will be the 4th cloud.
    The properties of this cloud are: cloud amount = 1., 
    emissivity = 1., reflectivity = absorptivity = 0.

</PRE>
</A><!-- END NOTES -->
<!--------------------------------------------------------------------->
<A NAME="PLANS">
<HR>
<H4>FUTURE PLANS</H4>
<!-- BEGIN PLANS -->
<PRE>

     None.

</PRE>
</A><!-- END PLANS -->
<!--------------------------------------------------------------------->

<HR>
</BODY>
</HTML>
